package com.southminority.ethnic.service.research;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.controller.research.vo.AwardVO;
import com.southminority.ethnic.pojo.Award;

import java.util.List;

/**
 * 获奖情况服务接口.
 * <p>
 * 定义了获奖情况模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 *
 * @author SouthMinority
 */
public interface AwardService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================
    
    /**
     * 分页查询已发布的获奖列表（用于前端列表页）.
     *
     * @param page          当前页码.
     * @param size          每页显示数量.
     * @param year          获奖年份 (可选, 精确匹配).
     * @param level         奖项级别 (可选, 精确匹配).
     * @param category      奖项类别 (可选, 精确匹配).
     * @return {@link PageResult<AwardVO>} 封装了分页信息的查询结果.
     */
    PageResult<AwardVO> getPublishedAwardPage(Integer page, Integer size, Integer year, String level, String category);

    /**
     * 获取单个已发布奖项的详细信息（用于前端详情页）.
     *
     * @param id 奖项的唯一标识ID.
     * @return {@link AwardVO} 包含完整信息的奖项视图对象.
     */
    AwardVO getAwardDetail(Long id);
    
    /**
     * 获取所有不重复的获奖年份列表（用于前端筛选菜单）.
     *
     * @return {@link List<Integer>} 年份列表.
     */
    List<Integer> getAwardYears();

    /**
     * 获取所有不重复的奖项级别列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 奖项级别字符串列表.
     */
    List<String> getAwardLevels();
    
    /**
     * 获取所有不重复的奖项分类列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 奖项分类字符串列表.
     */
    List<String> getAwardCategories();


    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================
    
    /**
     * 分页查询所有获奖信息（用于后台管理列表）.
     *
     * @param page          当前页码.
     * @param size          每页显示数量.
     * @param keyword       搜索关键词 (可选, 模糊匹配标题、项目名称).
     * @param category      奖项类别 (可选, 精确匹配).
     * @param level         奖项级别 (可选, 精确匹配).
     * @param status        状态 (可选, 1-启用, 0-禁用).
     * @return {@link PageResult<AwardVO>} 封装了分页信息的查询结果.
     */
    PageResult<AwardVO> getAwardPageForAdmin(Integer page, Integer size, String keyword, String category, String level, Integer status);

    /**
     * 根据ID获取获奖详情（用于后台管理编辑页）.
     *
     * @param id 奖项的唯一标识ID.
     * @return {@link AwardVO} 包含完整信息的奖项视图对象.
     */
    AwardVO getAwardDetailForAdmin(Long id);

    /**
     * 创建一个新的获奖记录.
     *
     * @param award 包含获奖所有信息的POJO对象.
     * @return {@link AwardVO} 创建成功后返回的奖项视图对象.
     */
    AwardVO createAward(Award award);
    
    /**
     * 更新一个已存在的获奖记录.
     *
     * @param id    要更新的奖项的ID.
     * @param award 包含更新后信息的POJO对象.
     * @return {@link AwardVO} 更新成功后返回的奖项视图对象.
     */
    AwardVO updateAward(Long id, Award award);
    
    /**
     * 根据ID删除一个获奖记录（逻辑删除）.
     *
     * @param id 要删除的奖项的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean deleteAward(Long id);
    
    /**
     * 批量删除获奖记录（逻辑删除）.
     *
     * @param ids 包含多个要删除的奖项ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    boolean batchDeleteAwards(List<Long> ids);
    
    /**
     * 更新指定获奖记录的状态.
     *
     * @param id     奖项的ID.
     * @param status 新的状态值 (例如: 1-启用, 0-禁用).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean updateAwardStatus(Long id, Integer status);
    
    /**
     * 设置或取消获奖记录的重点展示状态.
     *
     * @param id         奖项的ID.
     * @param isFeatured 是否重点展示 (1-是, 0-否).
     * @return 操作成功返回true, 否则返回false.
     */
    boolean setAwardFeatured(Long id, Integer isFeatured);
} 
